<div class="content">

  <h1>Simple Java Mail Features</h1>

  <section class="introduction">
    <p class="wide">
      Creating and sending emails is very simple with Simple Java Mail; you don't need to know about the mailing RFC, MimeMessage or any other low
      level <code class="inline">javax.mail</code> API. No anonymous inner classes needed and no <a
      href="http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mail.html">large frameworks</a> needed nor XML.
    </p>
    
    <h3>Features always used by default</h3>
    <p class="wide">
      Simple Java Mail will do some basic validation checks so that your email is always populated with enough data.
      It also checks for CRLF injection attacks. It even verifies email addresses against
      <a href="https://tools.ietf.org/html/rfc2822">RFC-2822</a> using the only complete
      <a href="https://github.com/bbottema/email-rfc2822-validator">rfc2822 validator in java</a> in the world.
      Simple Java Mail also takes care of all the
      <a href="https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html">connection and security properties</a> for you.
    </p>
  
    <h3>Builders all the way down</h3>
    <p class="wide">
        With all the possible ways to configure Email and Mailer instances, the library had only one option left to streamline API, avoid the
        <a href="http://codethataint.com/blog/telescoping-constructor-pattern-java/">Telescoping Constructor</a> anti-pattern and keep things
        managable: <a href="https://martinfowler.com/bliki/FluentInterface.html">fluent builders</a>.
      </p>
      <ol class="indent">
        <li>With fluent builders, we can tightly control <strong>valid combinations</strong>, logical <strong>decision paths</strong> and easily <strong>provide
          alternative methods</strong>.
        </li>
        <li>At the same time we can concentrate all mutation logic in the builders and produce mostly <strong>immutable objects</strong>.</li>
        <li>Finally, we're able to <strong>centralize our documentation</strong> around the builders and refer to it from wherever it is used.</li>
      </ol>
  </section>

  <section class="toc">
    <ul>
      <li><a simplePageScroll href="#section-basic-usage">Basic usage</a></li>
       <li><a simplePageScroll href="#section-builder-api" class="indent">About the fluent API with the Builder pattern</a></li>
       <li><a simplePageScroll href="#section-reusable-mailer" class="indent">Configure once, reuse many times</a></li>
       <li><a simplePageScroll href="#section-add-recipients" class="indent">Alternative API for almost everything</a></li>
       <li><a simplePageScroll href="#section-sending-asynchronously" class="indent">Asynchronous parallel batch sending</a></li>
       <li><a simplePageScroll href="#section-handling-async-result" class="indent">Handling asynchronous mailing result</a></li>
      <li><a simplePageScroll href="#section-custom-session">Sending with your own Session instance</a></li>
      <li><a simplePageScroll href="#section-custom-id">Setting a custom message ID on sent email</a></li>
      <li><a simplePageScroll href="#section-sent-id">Getting the generated email id after sending</a></li>
      <li><a simplePageScroll href="#section-ssl-tls">Sending with SSL and TLS</a></li>
        <li><a simplePageScroll href="#section-gmail" class="indent">SSL and TLS with Google mail</a></li>
      <li><a simplePageScroll href="#section-attachments">Adding attachments</a></li>
      <li><a simplePageScroll href="#section-embedding">Embedding images</a></li>
      <li><a simplePageScroll href="#section-custom-headers">Setting custom headers</a></li>
      <li><a simplePageScroll href="#section-custom-properties">Setting custom properties on the internal Session</a></li>
      <li><a simplePageScroll href="#section-icalendar-vevent">Sending a Calendar event (iCalendar vEvent)</a></li>
      <li><a simplePageScroll href="#section-session-access">Direct access to the internal Session</a></li>
      <li><a simplePageScroll href="#section-dkim">Signing emails with DKIM</a></li>
      <li><a simplePageScroll href="#section-return-receipt">Configure delivery / read receipt</a></li>
      <li><a simplePageScroll href="#section-email-validation">Validating Email Addresses</a></li>
      <li><a simplePageScroll href="#section-converting">Converting between email formats</a></li>
      <li><a simplePageScroll href="#section-bouncing-emails">Setting custom recipient for bouncing emails</a></li>
      <li><a simplePageScroll href="#section-reply-forward">Replying to and forwarding emails</a></li>
      <li><a simplePageScroll href="#section-proxy">Send using a proxy</a></li>
      <li><a simplePageScroll href="#section-connection-test">Testing a server connection</a></li>
    </ul>
  </section>

  <section class="roadmap">
    <h2>Roadmap</h2>
    <p>Currently everything we can think of is included!</p>
    <p>Got a suggestion? Please post it in the <a
      href="https://github.com/bbottema/simple-java-mail/issues"><strong>issue tracker</strong></a>.</p>
  </section>

  <a href="#section-basic-usage" id="section-basic-usage" class="section-link h2">&sect;</a>
  <h2>Basic usage</h2>

  <section>
    <div class="view">
      <p>
        Simply build an <code class="inline">Email</code>, populate it with your data, build a <code class="inline">Mailer</code> and send the Email
        instance. The mailer can be <a simplePageScroll
        href="#section-custom-session">created with your own <code class="inline">Session</code> instance as well</a>.
      </p>
      <p>
        A Mailer instance is reusable.
      </p>
    </div>

    <div class="side">
<pre><code>Email email = EmailBuilder.startingBlank()
    .from("Michel Baker", "m.baker@mbakery.com")
    .to("mom", "jean.baker@hotmail.com")
    .to("dad", "StevenOakly1963@hotmail.com")
    .withSubject("My Bakery is finally open!")
    .withPlainText("Mom, Dad. We did the opening ceremony of our bakery!!!")
    .buildEmail();

MailerBuilder
  .withSMTPServer("server", 25, "username", "password")
  .buildMailer()
  .sendMail(email);
</code></pre>
    </div>
  </section>


  <a href="#section-builder-api" id="section-builder-api" class="section-link h3">&sect;</a>
  <h3>About the fluent API with the Builder pattern</h3>

  <section>
    <p class="wide">
      The entry classes for the builders are EmailBuilder and MailerBuilder. For both, the first method affects the rest of the builder behavior.
    </p>
    <p class="wide">
      For <strong>EmailBuilder</strong>, the first method initializes the builder differently, either preconfiguring it
      (<code class="inline">EmailBuilder.copying()</code>, <code class="inline">EmailBuilder.replyingTo()</code>),
      or by setting values otherwise not possible
      (<code class="inline">EmailBuilder.forwarding()</code>).
    </p>
    <p class="wide">
      For <strong>MailerBuilder</strong>, the first method determines if you get a full builder API or a reduced API because you provided
      your own custom Session instance.<br/>
      <strong>If you provide your own session, a lot of properties are presumed to be preconfigured</strong>, such as SMTP server details.
    </p>
  </section>

  <a href="#section-reusable-mailer" id="section-reusable-mailer" class="section-link h3">&sect;</a>
  <h3>Configure once, reuse many times</h3>

  <section>
    <div class="view">
      <p>
        You can preconfigure a <code class="inline">Mailer</code> and use it many times.
      </p>
    </div>

    <div class="side">
<pre><code>Mailer inhouseMailer = new Mailer("server", 25, "username", "password");

inhouseMailer.sendMail(email);
inhouseMailer.sendMail(anotherEmail);
</code></pre>
      Or as preconfigured Spring bean:
      <pre><code>@Bean
public Mailer inhouseMailer() {{ '{' }}
        return MailerBuilder
            .withSMTPServer(...)
            .buildMailer();
{{ '}' }}
</code></pre>
      Or the default one from Spring support:
      <pre><code>
@Import(SimpleJavaMailSpringSupport.class)

@Autowired Mailer mailer; // configured completely using default properties
</code></pre>
    </div>
  </section>


  <a href="#section-add-recipients" id="section-add-recipients" class="section-link h3">&sect;</a>
  <h3>Alternative API for almost everything</h3>

  <section>
    <div>
      <p class="wide">
        Simple Java Mail has alternative ways to do things for almost everything...
      </p>
      <p class="wide">
        For example, when building an email, you can add recipients using
        <a href="https://github.com/bbottema/simple-java-mail/blob/master/src/main/java/org/simplejavamail/email/Recipient.java"><code class="inline">Recipient</code></a>
        objects, <a href="">RFC822 compiant <code class="inline">String</code> addresses</a> (each can be comma delimited and include optional nested names),
        <a href="http://geronimo.apache.org/maven/specs/geronimo-javamail_1.4_spec/1.6/apidocs/javax/mail/internet/InternetAddress.html"><code class="inline">InternetAddress</code></a>
        objects, collections of said addresses, default address names or fixed address names.
      </p>
    </div>

    <div>
      <pre><code>// You can add your own Recipient instances for example
currentEmailBuilder.withRecipients(yourRecipient1, yourRecipient2...);</code></pre>

      <pre><code>// or add comma / semicolon separated addresses (without names)
String list = "twister@sweets.com,blue.tongue@sweets.com;honey@sweets.com";
currentEmailBuilder.bcc(list);</code></pre>
      <pre><code>// or:
currentEmailBuilder.bccWithDefaultName("maintenance group", list);
currentEmailBuilder.bccWithFixedName("maintenance group", list); // same as .bcc()</code></pre>

      <pre><code>// what about a group with one deviating name?
String list = "bob@sweets.com, gene@sweets.com; Security Group &lt;security@sweets.com&gt;";
currentEmailBuilder.toWithDefaultName("stakeholders", list);
// bob and gene are named "stakeholders", "Security Group" get its own name</code></pre>
      <p>Through properties:</p>
      <pre><code class="language-properties">simplejavamail.defaults.bcc.name=
simplejavamail.defaults.bcc.address=twister@sweets.com,blue.tongue@sweets.com;honey@sweets.com
</code></pre>
    </div>

    <div>
      <div class="view">
        <p>To give you an idea of how flexible the API is for <strong>just adding recipients:</strong></p>
      </div>
      <div class="side">
      <pre><code class="small">// TO
.to(Recipient... recipients)
.to(Collection&lt;Recipient&gt; recipients)
.to(String name, String address)
.to(String oneOrMoreAddresses)
.to(String name, String... oneOrMoreAddressesEach)
.to(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.toMultiple(String... oneOrMoreAddressesEach)
.toMultiple(Collection&lt;String&gt; oneOrMoreAddressesEach)
.toWithFixedName(String name, String... oneOrMoreAddressesEach)
.toWithDefaultName(String name, String... oneOrMoreAddressesEach)
.toWithFixedName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.toWithDefaultName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.to(String name, InternetAddress address)
.to(InternetAddress address)
.to(String name, InternetAddress... oneOrMoreAddressesEach)
.toAddresses(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.toMultiple(InternetAddress... oneOrMoreAddressesEach)
.toMultipleAddresses(Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.toAddressesWithFixedName(String name, InternetAddress... oneOrMoreAddressesEach)
.toAddressesWithDefaultName(String name, InternetAddress... oneOrMoreAddressesEach)
.toAddressesWithFixedName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.toAddressesWithDefaultName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
// CC
.cc(Recipient... recipients)
.cc(Collection&lt;Recipient&gt; recipients)
.cc(String name, String address)
.cc(String oneOrMoreAddresses)
.cc(String name, String... oneOrMoreAddressesEach)
.cc(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.ccMultiple(String... oneOrMoreAddressesEach)
.ccAddresses(Collection&lt;String&gt; oneOrMoreAddressesEach)
.ccWithFixedName(String name, String... oneOrMoreAddressesEach)
.ccWithDefaultName(String name, String... oneOrMoreAddressesEach)
.ccWithFixedName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.ccWithDefaultName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.cc(String name, InternetAddress address)
.cc(InternetAddress address)
.cc(String name, InternetAddress... oneOrMoreAddressesEach)
.ccAddresses(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.ccMultiple(InternetAddress... oneOrMoreAddressesEach)
.ccMultipleAddresses(Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.ccAddressesWithFixedName(String name, InternetAddress... oneOrMoreAddressesEach)
.ccAddressesWithDefaultName(String name, InternetAddress... oneOrMoreAddressesEach)
.ccAddressesWithFixedName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.ccAddressesWithDefaultName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
// BCC
.bcc(Recipient... recipients)
.bcc(Collection&lt;Recipient&gt; recipients)
.bcc(String name, String address)
.bcc(String oneOrMoreAddresses)
.bcc(String name, String... oneOrMoreAddressesEach)
.bcc(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.bccMultiple(String... oneOrMoreAddressesEach)
.bccAddresses(Collection&lt;String&gt; oneOrMoreAddressesEach)
.bccWithFixedName(String name, String... oneOrMoreAddressesEach)
.bccWithDefaultName(String name, String... oneOrMoreAddressesEach)
.bccWithFixedName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.bccWithDefaultName(String name, Collection&lt;String&gt; oneOrMoreAddressesEach)
.bcc(String name, InternetAddress address)
.bcc(InternetAddress address)
.bcc(String name, InternetAddress... oneOrMoreAddressesEach)
.bccAddresses(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.bccMultiple(InternetAddress... oneOrMoreAddressesEach)
.bccMultipleAddresses(Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.bccAddressesWithFixedName(String name, InternetAddress... oneOrMoreAddressesEach)
.bccAddressesWithDefaultName(String name, InternetAddress... oneOrMoreAddressesEach)
.bccAddressesWithFixedName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
.bccAddressesWithDefaultName(String name, Collection&lt;InternetAddress&gt; oneOrMoreAddressesEach)
// GENERIC
.withRecipientsWithDefaultName(String defaultName, Collection&lt;String&gt; oneOrMoreAddressesEach, RecipientType recipientType)
.withRecipientsWithFixedName(String fixedName, Collection&lt;String&gt; oneOrMoreAddressesEach, RecipientType recipientType)
.withRecipientsWithDefaultName(String name, RecipientType recipientType, String... oneOrMoreAddressesEach)
.withRecipientsWithFixedName(String name, RecipientType recipientType, String... oneOrMoreAddressesEach)
.withRecipients(String name, boolean fixedName, RecipientType recipientType, String... oneOrMoreAddressesEach)
.withRecipients(String name, boolean fixedName, Collection&lt;String&gt; oneOrMoreAddressesEach, RecipientType recipientType)
.withAddressesWithDefaultName(String defaultName, Collection&lt;InternetAddress&gt; addresses, RecipientType recipientType)
.withAddressesWithFixedName(String fixedName, Collection&lt;InternetAddress&gt; addresses, RecipientType recipientType)
.withAddresses(String name, boolean fixedName, Collection&lt;InternetAddress&gt; addresses, RecipientType recipientType)
.withRecipients(Collection&lt;Recipient&gt; recipients)
.withRecipients(Recipient... recipients)
.withRecipients(Collection&lt;Recipient&gt; recipients, RecipientType fixedRecipientType)
.withRecipient(String singleAddress, RecipientType recipientType)
.withRecipient(String name, String singleAddress, RecipientType recipientType)
.withRecipient(Recipient recipient)</code></pre>
      </div>
    </div>
  </section>
  
  
  <a href="#section-handling-async-result" id="section-handling-async-result" class="section-link h3">&sect;</a>
  <h3>Handling asynchronous mailing result</h3>
  
  <section>
    <div class="view">
      <p>
        To handle the successful or erroneous result of an async sent email, you can utilize one of the response's async helpers:
        <em>Handlers</em> or <em>Future</em>.
      </p>
    </div>
    
    <div class="side">
      <p>Using Handlers:</p>
      <pre><code class="small">AsyncResponse asyncResponse = mailer.sendMail(email, true);
// also! mailer.testConnection(email, true);

asyncResponse.onSuccess(() -> System.out.println("Success"));
asyncResponse.onException((e) -> System.err.println("error"));
</code></pre>
      <p>Using Java's native Future:</p>
<pre><code class="small">Future<?> f = asyncResponse.getFuture();

// f.get() actually blocks until done, below is an example custom loop
// for checking result in a non-blocking way:
while (!f.isDone()) Thread.sleep(100);

// result is in, check it
try {{ '{' }}
  f.get(); // without the above loop, this would actually block until done
  System.err.println("success");
} catch (ExecutionException e) {{ '{' }}
  System.err.println("error");
}
</code></pre>
    </div>
  </section>
  
  
  <a href="#section-sending-asynchronously" id="section-sending-asynchronously" class="section-link h3">&sect;</a>
  <h3>Asynchronous parallel batch sending</h3>

  <section>
    <div class="view">
      <p>
        The default mode is to send emails synchronously, blocking execution until the email was processed completely and the STMP server sent a
        succesful result.
      </p>
      <p>
        You can also send anyschronously in parallel or batches, or simply send in a fire-and-forget way. If an authenticated proxy is used, the <a
        simplePageScroll href="#section-proxy">proxy bridging server</a> is kept alive until the last email has been sent.</p>
      <p>
        Depending on the SMTP server (and proxy server if used) this can greatly influence how fast emails are sent.
      </p>
    </div>

    <div class="side">
<pre><code>mailer.sendMail(email, /* async = */ true);
</code></pre>
      <p>Refer to the <a simplePageScroll [routerLink]="['/configuration']" href="#section-programmatic-api-other">configuration section</a>
         on how to set the thread pool size default.</p>
    </div>
  </section>


  <a href="#section-custom-session" id="section-custom-session" class="section-link h2">&sect;</a>
  <h2>Sending with your own Session instance</h2>

  <section>
    <div class="view">
      <p>
        If you prefer to use your own preconfigured <code class="inline">Session</code> instance and still benefit from Simple Java Mail, you can!
      </p>
    </div>

    <div class="side">
<pre><code>Email email = ...
...

MailerBuilder
    .usingSession(yourSession)
    .buildMailer()
    .sendMail(email);
</code></pre>
    </div>
  </section>


  <a href="#section-custom-id" id="section-custom-id" class="section-link h2">&sect;</a>
  <h2>Setting a custom message ID on sent email</h2>

  <section>
    <div class="view">
      <p>Message id's are normally generated by the underlying JavaMail framework, but you can provide your own if required.</p>
      <p>Just make sure your own id's conform to the <a href="https://tools.ietf.org/html/rfc5322#section-3.6.4">rfc5322</a> msg-id format standard</p>
    </div>

    <div class="side">
<pre><code>currentEmailBuilder.fixingMessageId("<123@456>");
</code></pre>
    </div>
  </section>


  <a href="#section-sent-id" id="section-sent-id" class="section-link h2">&sect;</a>
  <h2>Getting the generated email id after sending</h2>

  <section>
    <div class="view">
      <p>
        Sometimes you need the actual ID used in the MimeMessage that went out to the SMTP server.
        Luckily, it's very easy to retrieve it.
      </p>
    </div>

    <div class="side">
<pre><code>
mailer.sendMail(email); // id updated during sending!
email.getId(); // <1420232606.6.1509560747190@Cypher>
</code></pre>
    </div>
  </section>


  <a href="#section-ssl-tls" id="section-ssl-tls" class="section-link h2">&sect;</a>
  <h2>Sending with SSL and TLS</h2>

  <section>
    <div class="view">
      <p>
        Activating SSL or TLS is super easy. Just use the appropriate <code class="inline">TransportStrategy</code> enum.
      </p>
    </div>

    <div class="side">
<pre><code class="small">Email email = ...;

MailerBuilder.withTransportStrategy(TransportStrategy.SMTP); // default if omitted
MailerBuilder.withTransportStrategy(TransportStrategy.SMTPS);
MailerBuilder.withTransportStrategy(TransportStrategy.SMTP_TLS);
</code></pre>
    </div>
  </section>


  <a href="#section-gmail" id="section-gmail" class="section-link h3">&sect;</a>
  <h3>SSL and TLS with Google mail</h3>

  <section>
    <div class="view">
      <p>
        Here's an example of SSL and TLS using gMail.
      </p>
      <p>
        If you have two-factor login turned on, you need to generate an <a href="https://security.google.com/settings/security/apppasswords">application
                                                                                                                                             specific
                                                                                                                                             password</a>
        from your Google account.
      </p>
    </div>

    <div class="side">
<pre><code>MailerBuilder
  .withSMTPServer("smtp.gmail.com", 25, "your user", "your password")
  .withTransportStrategy(TransportStrategy.SMTP_TLS)
  // or
  .withSMTPServer("smtp.gmail.com", 587, "your user", "your password")
  .withTransportStrategy(TransportStrategy.SMTP_TLS)
  // or
  .withSMTPServer("smtp.gmail.com", 465, "your user", "your password")
  .withTransportStrategy(TransportStrategy.SMTPS);
</code></pre>
    </div>
  </section>


  <a href="#section-attachments" id="section-attachments" class="section-link h2">&sect;</a>
  <h2>Adding attachments</h2>

  <section>
    <div class="view">
      <p>
        You can add attachments very easily, but you'll have to provide the data yourself. Simple Java Mail accepts <code class="inline">byte[]</code>
        and <code class="inline">DataSource</code> objects.
      </p>
    </div>

    <div class="side">
<pre><code class="small">currentEmailBuilder
    .withAttachment("dresscode.txt", new ByteArrayDataSource("Black Tie Optional", "text/plain"))
    .withAttachment("location.txt", "On the moon!".getBytes(Charset.defaultCharset()), "text/plain")
    // ofcourse it can be anything: a pdf, doc, image, csv or anything else
    .withAttachment("invitation.pdf", new FileDataSource("invitation_v8.3.pdf"))
</code></pre>
    </div>
  </section>


  <a href="#section-embedding" id="section-embedding" class="section-link h2">&sect;</a>
  <h2>Embedding images</h2>

  <section>
    <div class="view">
      <p>
        Embedding images is simple, but you have to add the placeholders in the HTML yourself.
      </p>
    </div>

    <div class="side">
<pre><code class="small">currentEmailBuilder.withEmbeddedImage("smiley", new FileDataSource("smiley.jpg"));
// this example is included in the demo package in MailTestApp.java
String base64String = "iVBORw0KGgoAAAANSUhEUgAAA ...snip";
currentEmailBuilder.withEmbeddedImage("thumbsup", parseBase64Binary(base64String), "image/png");

// the corresponding HTML should contain the placeholders
&lt;p&gt;Let&#39;s go!&lt;/p&gt;&lt;img src=&#39;cid:thumbsup&#39;&gt;&lt;br/&gt;
&lt;p&gt;Smile!&lt;/p&gt;&lt;img src=&#39;cid:smiley&#39;&gt;
</code></pre>
    </div>
  </section>


  <a href="#section-custom-headers" id="section-custom-headers" class="section-link h2">&sect;</a>
  <h2>Setting custom headers</h2>

  <section>
    <div class="view">
      <p>
        Sometimes you need extra headers in your email because your email server, recipient server or your email client needs it. Or perhaps you have
        a proxy or monitoring setup in between mail servers. Whatever the case, adding headers is easy.
      </p>
    </div>

    <div class="side">
<pre><code>currentEmailBuilder
    .withHeader("X-Priority", 2);
    .withHeader("X-MC-GoogleAnalyticsCampaign", "halloween_sale");
    .withHeader("X-MEETUP-RECIP-ID", "71415272");
    .withHeader("X-my-custom-header", "foo");
    // or
    .withHeaders(yourHeadersMap);
</code></pre>
    </div>
  </section>


  <a href="#section-custom-properties" id="section-custom-properties" class="section-link h2">&sect;</a>
  <h2>Setting custom properties on the internal Session</h2>

  <section>
    <div class="view">
      <p>
        In case you need to modify the internal Session object itself, because you need a tailored configuration that is supported by the underlying
        <code class="inline">javax.mail</code>, that too is very easy.
      </p>
    </div>

    <div class="side">
<pre><code>currentMailerBuilder
    .withProperty("mail.smtp.timeout", 30 * 1000)
    .withProperty("mail.smtp.connectiontimeout", 10 * 1000)
    // or
    .withProperties(yourPropertiesObject)
    .withProperties(yourPropertiesMap)
</code></pre>
    </div>
  </section>
  
  
  <a href="#section-icalendar-vevent" id="section-icalendar-vevent" class="section-link h2">&sect;</a>
  <h2>Sending a Calendar event (iCalendar vEvent)</h2>

  <section>
    <div class="view">
      <p>
        You want to send a nice Calendar event (.ics) that a client such as Outlook processes nicely?
      </p>
      <p>Easy!</p>
      <p>
        Produce a Calendar event String (manually or by using a library such as <a href="https://github.com/ical4j/ical4j/wiki/Examples">ical4j</a>) and pass it to
        the <code class="inline">EmailBuilder</code>.
      </p>
      <p>
        See the <a href="https://github.com/bbottema/simple-java-mail/blob/master/src/test/java/demo/MailTestDemoApp.java#L69">test demo app</a> included in the
        Simple Java Mail source for a working example.
      </p>
    </div>

    <div class="side">
<pre><code class="small">// Create a Calendar with something like ical4j
Calendar icsCalendar = new Calendar();
icsCalendar.getProperties().add(new ProdId("-//Events Calendar//iCal4j 1.0//EN"));
icsCalendar.getProperties().add(Version.VERSION_2_0);

(..) // add attendees, organizer, end/start date and whatever else you need

// Produce calendar string
ByteArrayOutputStream bOutStream = new ByteArrayOutputStream();
new CalendarOutputter().output(icsCalendar, bOutStream);
String yourICalEventString = bOutStream.toString("UTF-8")

// Let Simple Java Mail handle the rest
currentEmailBuilder
    .withCalendarText(CalendarMethod.REQUEST, yourICalEventString)
</code></pre>
    </div>
  </section>


  <a href="#section-session-access" id="section-session-access" class="section-link h2">&sect;</a>
  <h2>Direct access to the internal Session</h2>

  <section>
    <div class="view">
      <p>
        For emergencies, you can also get a hold of the internal Session instance itself. <strong>You should never need this however</strong> and if
        you do it means Simple Java Mail failed to simplify the configuration process for you. <strong>Please let us know how we can help alleviate
                                                                                                       this need</strong>.
      </p>
    </div>

    <div class="side">
<pre><code>Mailer mailer = ...;

Session session = mailer.getSession();
// do your thing with session
</code></pre>
    </div>
  </section>


  <a href="#section-dkim" id="section-dkim" class="section-link h2">&sect;</a>
  <h2>Signing emails with DKIM</h2>

  <section>
    <div class="view">
      <p>
        Simple Java Mail also supports signing with <a href="http://blog.endpoint.com/2014/04/spf-dkim-and-dmarc-brief-explanation.html">DKIM</a>
        domain keys. It uses <a href="https://github.com/markenwerk/java-utils-mail-dkim">java-utils-mail-dkim</a> (dependency packaged along) to
        perform the DNS DKIM record check on the given domain.
      </p>
      <p>DKIM is an optional feature and if you want to use it, you need to include the following dependency in your project:</p>
      <pre><code class="small language-xml">&lt;dependency&gt;
    &lt;groupId&gt;net.markenwerk&lt;/groupId&gt;
    &lt;artifactId&gt;utils-mail-dkim&lt;/artifactId&gt;
    &lt;version&gt;X.X.X&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
    </div>

    <div class="side">
<pre><code>currentEmailBuilder.
    .signWithDomainKey(
       privateKey byte[] / File / InputStream,
       "your_domain.org",
       "your_selector");

mailer.sendMail(signedEmail);
</code></pre>
      You can also directly use the helper method:
      <pre><code>Mailer.signMessageWithDKIM(mimeMessageToSign, emailContainingSigningDetails);</code></pre>
    </div>
  </section>


  <a href="#section-return-receipt" id="section-return-receipt" class="section-link h2">&sect;</a>
  <h2>Configure delivery / read receipt</h2>

  <section>
    <div class="view">
      <p>
        For servers and clients that support it (mostly Outlook at offices), Simple Java Mail has built in support for
        <a href="https://www.chilkatsoft.com/p/p_313.asp">'delivery receipt' and 'read receipt'</a>, which is configured
        through the headers <code>Return-Receipt-To</code> and <code>Disposition-Notification-To</code> respectively.
      </p>
      <p>
        You can explicitly define the email address to return the receipts to or else Simple Java Mail will default
        to the <em>replyTo</em> address if available or else the <em>fromAddress</em>.
      </p>
    </div>

    <div class="side">
<pre><code class="small">currentEmailBuilder.
    .withDispositionNotificationTo();
    .withReturnReceiptTo();
    // or:
    .withDispositionNotificationTo(new Recipient("name", "address@domain.com"));
    .withReturnReceiptTo(new Recipient("name", "address@domain.com"));
</code></pre>
    </div>
  </section>


  <a href="#section-email-validation" id="section-email-validation" class="section-link h2">&sect;</a>
  <h2>Validating Email Addresses</h2>

  <section>
    <div class="view">
      <p>
        Simple Java Mail can validate your email addresses. It's not just a simple regex check, but a complete and robust full validation against <a
        href="https://tools.ietf.org/html/rfc2822">RFC-2822</a>. It does this by including <a
        href="https://github.com/bbottema/email-rfc2822-validator">email-rfc2822-validator</a> in the library.
      </p>
      <p>
        Address validation is performed automatically when sending emails, but you can also directly perform validations.
      </p>
    </div>

    <div class="side">
<pre><code>currentMailerBuilder
    .withEmailAddressCriteria(EmailAddressCriteria.RFC_COMPLIANT)
    // or
    .withEmailAddressCriteria(
      of(ALLOW_QUOTED_IDENTIFIERS, ALLOW_PARENS_IN_LOCALPART)
    )
    // or
    .clearEmailAddressCriteria() // turn off validation
    .resetEmailAddressCriteria() // reset to default
</code></pre>
      <pre><code>// you can also directly perform validations.
mailer.validate(email);

// or use the underlying library included for this
EmailAddressValidator.isValid("your_address@domain.com",
   EmailAddressCriteria.RFC_COMPLIANT);

// or, fine-tuned to be less strict:
EmailAddressValidator.isValid("your_address@domain.com",
   of(ALLOW_QUOTED_IDENTIFIERS, ALLOW_PARENS_IN_LOCALPART));
</code></pre>
    </div>
  </section>



  <a href="#section-generate-converting" id="section-converting" class="section-link h2">&sect;</a>
  <h2>Converting between, Email, MimeMessage, EML and Outlook .msg</h2>

  <section>
    <div class="view">
      <p>
        With Simple Java Mail you can easily convert to other types.
      </p>
      <p>
        For example, if you need a MimeMessage, you can convert <code class="inline">Email</code> objects, EML data and even Outlook .msg files.
      </p>
      <p>
        If you already have a MimeMessage, you can it into an Email instance, complete with embedded images and attachments, headers intact.
      </p>
      <p>
        You can even build a mass Outlook .msg to <a href="http://forensicswiki.org/wiki/EML">EML</a> converter if you like!
      </p>
      <p>
        To enable Outlook message parsing support, include the
        <a href="https://github.com/bbottema/outlook-message-parser">outlook-message-parser</a> dependency:
      </p>
      <pre><code class="small language-xml">&lt;dependency&gt;
    &lt;groupId&gt;org.simplejavamail&lt;/groupId&gt;
    &lt;artifactId&gt;outlook-message-parser&lt;/artifactId&gt;
    &lt;version&gt;X.X.X&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
    </div>

    <div class="side">
<pre><code class="small">// from Email
String eml =              EmailConverter.emailToEML(yourEmail);
MimeMessage mimeMessage = EmailConverter.emailToMimeMessage(yourEmail);
MimeMessage mimeMessage = EmailConverter.emailToMimeMessage(yourEmail, yourSession);

// from MimeMessage
Email email =             EmailConverter.mimeMessageToEmail(yourMimeMessage);
String eml =              EmailConverter.mimeMessageToEML(yourMimeMessage);

// from EML
Email email =             EmailConverter.emlToEmail(emlDataString);
MimeMessage mimeMessage = EmailConverter.emlToMimeMessage(emlDataString);
MimeMessage mimeMessage = EmailConverter.emlToMimeMessage(emlDataString, yourSession);

// from Outlook .msg
Email email =             EmailConverter.outlookMsgToEmail(readToString("yourMessage.msg"));
Email email =             EmailConverter.outlookMsgToEmail(new File("yourMessage.msg"));
Email email =             EmailConverter.outlookMsgToEmail(getInputStream("yourMessage.msg"));
String eml =              EmailConverter.outlookMsgToEML(readToString("yourMessage.msg"));
String eml =              EmailConverter.outlookMsgToEML(new File("yourMessage.msg"));
String eml =              EmailConverter.outlookMsgToEML(getInputStream("yourMessage.msg"));
MimeMessage mimeMessage = EmailConverter.outlookMsgToMimeMessage(readToString("yourMessage.msg"));
MimeMessage mimeMessage = EmailConverter.outlookMsgToMimeMessage(new File("yourMessage.msg"));
MimeMessage mimeMessage = EmailConverter.outlookMsgToMimeMessage(getInputStream("yourMessage.msg"));
</code></pre>
    </div>
  </section>


  <a href="#section-bouncing-emails" id="section-bouncing-emails" class="section-link h2">&sect;</a>
  <h2>Setting custom recipient for bouncing emails</h2>

  <section>
    <div class="view">
      <p>
        For bouncing emails, you can provide a hint to the SMTP server to which bouncing emails should be returned.
        This is also known as the Return-Path or Envelope FROM and is set on the Session instance with the property
        <code class="inline">mail.smtp.from</code>.
      </p>
      <p>
        Simple Java Mail offers a convenience method to set this property.
      </p>
    </div>

    <div class="side">
<pre><code>// in similar fashion to setting replyTo address:
currentEmailBuilder
    .withBounceTo(aRecipientInstance) // or
    .withBounceTo("Bob", "bob.techdesk@candyshop.com")
    // or using one of the many alternative methods...
</code></pre>
    </div>
  </section>


  <a href="#section-reply-forward" id="section-reply-forward" class="section-link h2">&sect;</a>
  <h2>Replying to and forwarding emails</h2>

  <section>
    <div class="view">
      <p>
        If you have an email you want to reply to or wish to forward, the <code class="inline">EmailBuilder</code>
        has you covered.
      </p>
      <br />
      <div>
        <p>
          <strong>Note:</strong> due to the nature of the underlying JavaMail framework (also see
            <a href="https://javaee.github.io/javamail/FAQ#reply">reply</a> /
            <a href="https://javaee.github.io/javamail/FAQ#forward">forward</a>):
        </p>
        <ul class="indent">
          <li>In case of replying, the original email is quoted in the body of the reply itself.</li>
          <li>In case of forwarding, the original email is included as a separate body inside the forward.</li>
        </ul>
      </div>
    </div>

    <div class="side">
      <p>Replying to an email:</p>
<pre><code>EmailBuilder
    .replyingTo(receivedEmail) // Email or MimeMessage
    .from("dummy@domain.com")
    .prependText("Reply body. Original email included below")
    .buildEmail();
</code></pre>
      <p>Forwarding an email:</p>
<pre><code>EmailBuilder
    .forwarding(receivedEmail) // Email or MimeMessage
    .from("dummy@domain.com")
    .text("Hello? This is Forward. See below email:")
    .buildEmail();
</code></pre>
    </div>
  </section>


  <a href="#section-proxy" id="section-proxy" class="section-link h2">&sect;</a>
  <h2>Send using a proxy</h2>

  <section>
    <div>
      <p class="wide">
        Simple Java Mail supports sending emails through a proxy. It is also the only java mailing framework in the world that supports sending emails
        through <strong>authenticated</strong> proxies. The reason for this is that the underlying native
        <a href="https://java.net/projects/javamail/pages/Home">Javax Mail framework</a> supports anonymous SOCKS5 proxies, but
        <a href="http://www.oracle.com/technetwork/java/javamail/faq/index.html#proxy">not authenticated proxies</a>.
      </p>
      <p class="wide">
        To make this work with authentication, Simple Java Mail uses a trick: it sets up a temporary anonymous proxy server for Javax Mail to connect
        to and then the bridge relays the connection to the target proxy performing the authentication outside of Javax Mail.
      </p>
      <p class="wide">
        This temporary server is referred to as the <strong>Proxy Bridging Server</strong>.
      </p>
    </div>

    <div>
<pre><code>// anonymous proxy
currentMailerBuilder.withProxy("proxy.host.com", 1080)

// authenticated proxy
currentMailerBuilder.withProxy("proxy.host.com", 1080, "proxy username", "proxy password");
</code></pre>
      <p>Refer to the <a simplePageScroll [routerLink]="['/configuration']" href="#section-other-settings">configuration section</a>
         on how to set proxy server defaults and the port on which the proxy bridge runs.</p>
    </div>
  </section>


  <a href="#section-connection-test" id="section-connection-test" class="section-link h2">&sect;</a>
  <h2>Testing a server connection</h2>

  <section>
    <div class="view">
      <p>
        If you just want to do a connection test using your current configuration, including transport strategy and (authenticated)
        proxy, Simple Java Mail got you covered.
      </p>
      <p>
        The connection test can also be done asynchronously and the result can be handled asynchronously as well. Take a look at
        <a simplePageScroll href="#section-handling-async-result">Handling asynchronous mailing result</a>.
      </p>
    </div>

    <div class="side">
<pre><code>// configure your mailer
Mailer mailer = ...;

// perform connection test
mailer.testConnection(/* async? */); // no error means success
</code></pre>
    </div>
  </section>

</div>
